/**
 * 
 * Copyright 2009 Marco Speranza <marco.speranza79@gmail.com>
 *    
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *   
 * http://www.apache.org/licenses/LICENSE-2.0
 *  
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.commons.database.util.jquerycreator;

import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;

// TODO: Auto-generated Javadoc
/**
 * Interfaccia per la creazione delle query sql.
 * 
 * @author Marco Speranza
 */
public interface IDataBaseQueryCreator {

    /**
     * Cancella tutto.
     */
    public void clear();

    /**
     * Chiude tutte le risorse.
     * 
     * @throws SQLException
     *             the SQL exception
     */
    public void closeAll() throws SQLException;

    /**
     * Chiude tutte le risorse ma non rilascia la connessione.
     * 
     * @throws SQLException
     *             the SQL exception
     */
    public void closeAllWithoutConnection() throws SQLException;

    /**
     * Esegue la commit sulla connessione aperta.
     * 
     * @throws SQLException
     *             the SQL exception
     */
    public void commit() throws SQLException;

    /**
     * Esegue la query e immagazina il result set con i valori di ritorno.
     * <br/>
     * <b>Attenzione:</b> utilizzare il metodo <b><code>closeAll()</code></b> dopo aver
     * recuperato tutte le righe, per liberare le risorse.
     * <br/><br/>
     * <b> in caso di una SQLException viene effettuata la rollback sulla connessione.</b>
     * @throws SQLException
     *             the SQL exception
     */
    public void executeQuery() throws SQLException;

    /**
     * Esegue la query di update e chiude le risorse la datasource.
     * <br/>
     * <b>Attenzione:</b> utilizzare il metodo <b><code>closeAll()</code></b> dopo aver
     * recuperato tutte le righe, per liberare le risorse.
     * <br/><br/>
     * <b> in caso di una SQLException viene effettuata la rollback sulla connessione.</b> 
     * 
     * @return torna il numero di righe aggiornate.
     * 
     * @throws SQLException
     *             the SQL exception
     */
    public int executeUpdate() throws SQLException;

    /**
     * Esegue la query di update e immagazina il result set con i valori di
     * ritorno. N.B. per avere i valori di ritono utilizzare il costruttore
     * {@link DataBaseQueryCreator(int)}
     * 
     * <br/>
     * <b>Attenzione:</b> utilizzare il metodo <b><code>closeAll()</code></b> dopo aver
     * recuperato tutte le righe, per liberare le risorse.
     * <br/><br/>
     * <b> in caso di una SQLException viene effettuata la rollback sulla connessione.</b>
     * 
     * @param columnIndex
     *            l'array contenete gli indici delle colonne di cui si vuole il
     *            valore autogenerato
     * 
     * @return torna il numero di righe aggiornate.
     * 
     * @throws SQLException
     *             the SQL exception
     */
    public int executeUpdate(int[] columnIndex) throws SQLException;

    /**
     * Crea lo statement sql con la query che e' stata settata e setta tutti i
     * parametri della query stessa. La query deve essere setta con il metodo
     * <code>setSql()</code>
     * 
     * @throws SQLException
     *             the SQL exception
     */
    public void fillQuery() throws SQLException;

    /**
     * Sostituisce i '?' con i valori associati.
     * 
     * @param stmt
     *            the stmt
     * 
     * @return the prepared statement
     * 
     * @throws SQLException
     *             in caso di errore chiude tutte le connessioni eventualmente
     *             aperte.
     */
    public PreparedStatement fillQuery(PreparedStatement stmt)
	    throws SQLException;

    /**
     * Crea lo statement sql con la query in input e setta tutti i parametri
     * della query stessa.
     * 
     * @param sql
     *            La query.
     * 
     * @throws SQLException
     *             the SQL exception
     */
    public void fillQuery(String sql) throws SQLException;

    /**
     * Torna una stringa contenente la query con i valori correttamente
     * inseriti.
     * 
     * @return the filled query
     */
    public String getFilledQuery();

    /**
     * Torna la posizione corrente del contatore interno che identifica i '?'.
     * 
     * @return the position
     */
    public int getPosition();

    /**
     * Torna il result set creato.
     * 
     * <b>Attenzione: utilizzare il metodo <code>closeAll()</code> dopo aver
     * recuperato tutte le righe, per liberare le risorse.</b>
     * 
     * @return the result set
     */
    public ResultSet getResultSet();

    /**
     * Torna la query sql iniziale.
     * 
     * @return the sql
     */
    public String getSql();

    /**
     * Crea uno statement sql e torna il suo reference. Per la creazione dello
     * statement viene utilizzata la stringa sql settata con il metodo
     * <code> setSql() </code>
     * 
     * @return Lo statement creato
     * 
     * @throws SQLException
     *             the SQL exception
     */
    public PreparedStatement makePreparedStatement() throws SQLException;

    /**
     * Crea uno statement sql e torna il suo reference.
     * 
     * @param sql
     *            la query che verra' usata per la creazione dello statemet.
     * 
     * @return Lo statement creato
     * 
     * @throws SQLException
     *             the SQL exception
     */
    public PreparedStatement makePreparedStatement(String sql)
	    throws SQLException;

    /**
     * inserisce un oggetto.
     * 
     * @param value
     *            the value
     * @param type
     *            il tipo sql che deve essere inserito. <br>
     *            i valori accetati sono <code>java.sql.Types</code>
     * 
     * @return the DataBaseQueryCreatorBean
     */
    public DataBaseQueryCreatorBean put(Object value, int type);


    /**
     * Setta il flag che indica se il data dource deve tornare i valori
     * autogenerati. Accetta uno di questi due valori:
     * <code>Statement.RETURN_GENERATED_KEYS</code> or
     * <code>Statement.NO_GENERATED_KEYS</code>
     * 
     * @param autogeneratedKey
     *            the autogenerated key
     */
    public void setAutogeneratedKey(int autogeneratedKey);
    
    /**
     * Setta il datasource manager per la gestione della connessione.
     * 
     * @param datasourceManager
     *            una instanza del datasource manager.
     */
    public void setDataSourceManager(IDatasourceManager datasourceManager);

    /**
     * Setta la query sql da riempire.
     * 
     * @param sql
     *            the sql to set
     */
    public void setSql(String sql);


}
